<!DOCTYPE HTML>
<html lang="en">
<head>
<title>#Include / #IncludeAgain - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The #Include and #IncludeAgain directives cause the script to behave as though the specified file's contents are present at this exact position." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>#Include[Again]</h1>

<p>Causes the script to behave as though the specified file's contents are present at this exact position.</p>

<pre class="Syntax">
<span class="func">#Include</span> FileOrDirName
<span class="func">#Include</span> &lt;LibName&gt;
<span class="func">#IncludeAgain</span> FileOrDirName
</pre>
<h2>Parameters</h2>
<dl>

  <dt>FileOrDirName</dt>
  <dd><p>The path of a file or directory as explained below. This <strong>must not</strong> contain double quotes, wildcards, or references to non-built-in variables. <a href="_EscapeChar.htm">Escape sequences</a> other than semicolon (<strong>`;</strong>) must not be used, nor are they needed because characters such as percent signs are treated literally.</p>
  <p>Percent signs which are not part of a valid variable reference are interpreted literally. All built-in variables are valid, except for <a href="../misc/ErrorLevel.htm">ErrorLevel</a>, <a href="../Scripts.htm#cmd_args">A_Args</a> and the <a href="../Scripts.htm#cmd_args_old">numbered variables</a>. Prior to <span class="ver">[v1.1.28]</span>, only <a href="../Variables.htm#ScriptDir">%A_ScriptDir%</a>, <a href="../Variables.htm#AppData">%A_AppData%</a>, <a href="../Variables.htm#AppDataCommon">%A_AppDataCommon%</a> and <span class="ver">[in v1.1.11+]</span> <a href="../Variables.htm#LineFile">%A_LineFile%</a> were supported.</p>
  <p>Known limitation: When compiling a script, variables are evaluated by the compiler and may differ from what the script would return when it is finally executed. Ahk2Exe v1.1.30.00 and earlier only support the four variables listed above. <span class="ver">[v1.1.30.01+]:</span> The following variables are also supported: <a href="../Variables.htm#AhkPath">A_AhkPath</a>, <a href="../Variables.htm#ComputerName">A_ComputerName</a>, <a href="../Variables.htm#ComSpec">A_ComSpec</a>, <a href="../Variables.htm#Desktop">A_Desktop</a>, <a href="../Variables.htm#DesktopCommon">A_DesktopCommon</a>, <a href="../Variables.htm#IsCompiled">A_IsCompiled</a>, <a href="../Variables.htm#IsUnicode">A_IsUnicode</a>, <a href="../Variables.htm#MyDocuments">A_MyDocuments</a>, <a href="../Variables.htm#ProgramFiles">A_ProgramFiles</a>, <a href="../Variables.htm#Programs">A_Programs</a>, <a href="../Variables.htm#ProgramsCommon">A_ProgramsCommon</a>, <a href="../Variables.htm#ScriptFullPath">A_ScriptFullPath</a>, <a href="../Variables.htm#ScriptName">A_ScriptName</a>, <a href="../Variables.htm#Space">A_Space</a>, <a href="../Variables.htm#StartMenu">A_StartMenu</a>, <a href="../Variables.htm#StartMenuCommon">A_StartMenuCommon</a>, <a href="../Variables.htm#Startup">A_Startup</a>, <a href="../Variables.htm#StartupCommon">A_StartupCommon</a>, <a href="../Variables.htm#Tab">A_Tab</a>, <a href="../Variables.htm#Temp">A_Temp</a>, <a href="../Variables.htm#UserName">A_UserName</a>, <a href="../Variables.htm#WinDir">A_WinDir</a>.</p>
    <p><strong>File:</strong> The name of the file to be included, which is assumed to be in the startup/working directory if an absolute path is not specified (except for <a href="../Scripts.htm#ahk2exe">Ahk2Exe</a>, which assumes the file is in the script's own directory). Note: <a href="SetWorkingDir.htm">SetWorkingDir</a> has no effect on #Include because #Include is processed before the script begins executing.</p>
      <p><strong>Directory:</strong> Specify a directory instead of a file to change the working directory used by all subsequent occurrences of #Include and <a href="FileInstall.htm">FileInstall</a>. Note: Changing the working directory in this way does not affect the script's initial working directory when it starts running (<a href="../Variables.htm#WorkingDir">A_WorkingDir</a>). To change that, use <a href="SetWorkingDir.htm">SetWorkingDir</a> at the top of the script.</p></dd>

  <dt>LibName</dt>
  <dd><p><span class="ver">[AHK_L 57+]:</span> A library file or function name. For example, <code>#include &lt;lib&gt;</code> and <code>#include &lt;lib_func&gt;</code> would both include lib.ahk from one of the <a href="../Functions.htm#lib">function library folders</a>. <em>LibName</em> cannot contain variable references.</p></dd>

</dl>
<h2>Remarks</h2>
<p>A script behaves as though the included file's contents are physically present at the exact position of the #Include directive (as though a copy-and-paste were done from the included file). Consequently, it generally cannot merge two isolated scripts together into one functioning script.</p>
<p>#Include ensures that <em>FileName</em> is included only once, even if multiple inclusions are encountered for it. By contrast, #IncludeAgain allows multiple inclusions of the same file, while being the same as #Include in all other respects.</p>
<p>The <em>FileName</em> parameter may optionally be preceded by <code>*i</code> and a single space, which causes the program to ignore any failure to read the included file. For example: <code>#Include *i SpecialOptions.ahk</code>. This option should be used only when the included file's contents are not essential to the main script's operation.</p>
<p>Lines displayed in the main window via <a href="ListLines.htm">ListLines</a> or the menu View-&gt;Lines are always numbered according to their physical order within their own files. In other words, including a new file will change the line numbering of the main script file by only one line, namely that of the #Include line itself (except for <a href="../Scripts.htm#ahk2exe">compiled scripts</a>, which merge their included files into one big script at the time of compilation).</p>
<p>#Include is often used to load <a href="../Functions.htm">functions</a> defined in an external file. Unlike subroutine labels, <a href="../Functions.htm">functions</a> can be included at the very top of the script without affecting the <a href="../Scripts.htm#auto">auto-execute section</a>.</p>
<p>Like other # directives, #Include cannot be executed conditionally. In other words, this example would not work:</p>
<pre>if (x = 1)
    #Include SomeFile.ahk  <em>; This line takes effect regardless of the value of x.</em>
    y := 2  <em>; And this line would belong to the IF above, since # directives cannot belong to IFs.</em></pre>
<p>Files can be automatically included (i.e. without having to use #Include) by calling a <a href="../Functions.htm#lib">library function</a> by name.</p>
<p><span class="ver">[v1.1.11+]:</span> Use <code><a href="../Variables.htm#LineFile">%A_LineFile%</a>\..</code> to refer to the directory which contains the current file, even if it is not the main script file.  For example, <code>#Include %A_LineFile%\..\other.ahk</code>. <span class="ver">[v1.1.28+]:</span> <code><a href="../Variables.htm#AhkPath">%A_AhkPath%</a>\..</code> can be used to refer to the directory containing AutoHotkey.exe.</p>

<h2>Related</h2>
<p><a href="../Functions.htm#lib">Libraries of Functions</a>, <a href="../Functions.htm">Functions</a>, <a href="FileInstall.htm">FileInstall</a></p>
<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>#Include C:\My Documents\Scripts\Utility Subroutines.ahk
#Include %A_ScriptDir%  <em>; Changes the working directory for subsequent #Includes and FileInstalls.</em>
#Include C:\My Scripts  <em>; Same as above but for an explicitly named directory.</em></pre>
</div>

</body>
</html>
